LOGIC 2000 February/LogicCd--feb.2000-mac-cdr.iso/Apple II/Utilities/deimage/DEIMAGE.DOC

Text File | 1994-07-05 | 9.3 KB | 202 lines | [TEXT/pdos]

DEIMAGE 0.1

WARNING:  DeImage is buggy and unfinished, though this is
probably as far as I'm going to finish it.  It definitely won't
work for Integer Basic or Text Files.  It seems to work for
AppleSoft and Binary files.  Use it at your own risk.  Have a
nice day.

DeImage is a little ProDOS BASIC program I wrote for myself to
get the files out of Apple ][ DOS 3.3 143k image files used with
Kevin Lund's excellent emulator for the Mac, Stop the Madness!
It also appears to work with the images created for some
PC-based Apple ][ emulators which use the same format as STM.

It requires:
ProDOS 8 and BASIC.SYSTEM (I assume any version of ProDOS, but I
don't know for sure)
An STM image file of a standard DOS 3.3 disk, located on a
mounted ProDOS volume (i.e. a 3.5" floppy or a hard drive)
Some patience with the interface

ModWare:
I'm releasing this program as ModWare.  This means not only are
you free to copy it, give it to friends, feed it to your dog
etc., but you are actively encouraged to improve the software
(easy to do, since it's in BASIC) and re-upload it.  I only ask
that
1) you increase the version number accordingly,
2) that you leave these docs in some form, though you are of
course free to modify them,
3) that you describe your changes in the docs,
4) you leave my name and the names of any other modifiers before
you in the docs and program lines 990-999.
5) you test your changes so that they are (somewhat) reliable, and warn about anything that needs to be warned about.
Thanks!

Not that this program is really such a big deal anyway, but, hey,
I suppose you have to start somewhere.

Since I wrote the program for me, I didn't take extensive pains
to implement a swift interface.  I thought it might be useful to
users of STM, however, so I'm uploading it anyway.

Using DeImage:
Actually, it's fairly straightforward.  When you run DeImage, it
will ask you for the name of the file.  If it's in a directory or
on a volume other than the one you're in, include that too.   You
will then be asked for the filetype; pressing return defaults to
BIN ($06).

If DeImage can't find the file, it complains and lets you try
again.  User-friendliness abounds!  If you're sure you've got the
name right, make sure you've got the filetype right, too.

Otherwise you should be presented with a catalog of your DOS 3.3
disk image.  It's not the fastest program in the world, I know --
it's reading 256-byte chunks at a time.  You are advised to have
your image file on a hard disk or RAM disk for tolerable speed.

You'll note on the left-hand side of the screen are numbers
assigned to the files.  If any numbers are skipped, it's because
there was a catalog entry marked as being deleted.  Don't worry
about it.

After the catalog is finished, you'll be asked if you want to
extract all the files.  If you say "Y", it's pretty simple -- it
goes through, one by one, and saves each file to whatever
directory you were in when you ran the program.  (If you want to
specify a default save directory, add PRINT D$"PREFIX
/WHEREVER/WHATEVER" at the beginning of the program.)

If you answer "N" to the above question, you'll be asked which
files you want.  Enter their numbers, one at a time, pressing
return after each one, and when you're done press return by
itself.  I told you, the interface sucks.

Then it should go through and extract all the files you chose.
 As it extracts, you'll notice three numbers pop up -- the first
is the track it's on in the image, the second is the sector, and
the third is the number of sectors (256 bytes) it's loaded.  This
is chiefly for amusement/debugging value (whee).

If along the way DeImage encounters a file it can't neatly
convert into a ProDOS filename, it complains at you at asks you
to enter a new name.  What you'll discover unfortunately is that
you'll probably get a RETURN WITHOUT GOSUB error once it's
extracted.  This is because it seems as if ONERR GOTO kills
whatever's on the stack in terms of GOSUB and FOR..NEXT, and I
can't remember what to do about it and don't care that much.
Anyway, if this happens, just be patient and type RUN, and get
the rest of the files you wanted.  Or better still, fix it.  I think all it takes is a well-placed RESUME command.

That's it.  Now for the bad parts.

Caveats:
DeImage has had LIMITED testing.  It seems to work okay for me,
but I haven't pushed it.  Use it completely at your own risk.  I
don't think the program itself can do any harm, but conceivably a
corrupted extraction could.  Hopefully you won't get any.  You
can also minimize risk by not trying to run questionable files
under ProDOS (see below).

If you have two similar DOS 3.3 filenames on your original disk,
one may overwrite the other when saved to ProDOS.  For example,
if you have a file called LUNAR LANDER followed by a file called
LUNAR.LANDER, they both get the same name in ProDOS and so the
second one obliterates the first.  Similarly, if you have two DOS
3.3 files whose first 15 characters are the same, the same thing
will happen.  Presently, the only workaround is to extract one,
rename it in ProDOS, then extract the other, which is a pain.  I
suggest you modify the program to deal with it somehow.

I have only really tested the extraction of A (AppleSoft BASIC)
and B (binary) files.  T (text files) are likely to be iffy --
especially random-access ones.  If DeImage encounters anything
else -- I, S, R, and the "special" A and B -- it will probably
save them as BIN files if it doesn't conk out completely.  Just
be aware, and fix it if you like.

Many programs designed to run under DOS 3.3 may not run under
ProDOS, so don't be surprised when they don't.  Particularly be
aware of any programs that do disk calls or that use strange
loaders -- they definitely won't work.  They should work if you
use your favorite utility to convert them back to DOS 3.3,
however.  Stand-alone basic or binary programs may work fine
under ProDOS, however.

This program is ONLY intended for use for standard DOS 3.3 disk
images with standard file entries stored in a standard catalog.
There's some error checking for this, but it's not foolproof, so
don't try extracting something which has a sector size of 0 and
whose name is 30 inverse @'s.

Um, that's about as much as I can think of, so if there's
anything I seem to have left out, well, ok, so what.

Send questions, comments, and whatever to me at
[e-mail].  If you find this program actually useful,
I'd like to know...I'd also like some cool images, if you have
any.

revision history:
Ivan Drucker 5/24/94 v0.01 -- first release.  Crude but
serviceable, if you count inoperable as serviceable.
7/4/94 v0.1 -- Fixed some minor bugs, such as no D$=CHR$(4),
clever, huh.  No major changes, those are for you to do.  I don't really plan to ever look at this program again, actually, except when I use it.

Also by me for STM hounds:
UnImage Pro (catchy title, huh?), which, as some have requested,
converts an STM image back into a disk, and is therefore useable
with any disk image, not just a standard 3.3.

Also:  UnForkIt, a program to split a forked file into two
standard files under ProDOS 8.  Unlike similar programs, it
directly modifies the directory structure rather than copying the
forks to new files.  This brings with it added speed and risk,
without which life would be dull.

How DeImage works, for those who care:
Basically, the program makes use of ProDOS' fabulously flexible
BLOAD command to simulate reading sectors under DOS 3.3.

It starts by reading the catalog track (Volume Table of Contents,
or VTOC), which is on a standard disk track $11, sectors $0-F.
This is where it reads the catalog and displays it to you.
It loads this into memory at $2000, if I'm not mistaken, and then
works with it in RAM.

When you select the files you want, it finds the track and sector
where the file starts, which contains a track/sector list.  This
is a list of track/sector pairs in the order in which they are to
be read off the disk.  I think it loads the T/S list into $1F00.
If the T/S list is more than one sector, as it is for large
files, the next page is read into $1E00, and so on.

DeImage then follows the track/sector list, loading tracks and
sectors into memory in order at $3000.  When it reaches the end
or fills the buffer (ends at $8FFF), it BSAVES the file.  ProDOS
BSAVE is flexible, so it can save multiple chunks into the same
file.

Only for those inspecting the program and wondering why the hell
I did things THAT way:
In DOS 3.3, binary files start with four bytes which indicate the
address the file is to load at and the length of it.  AppleSoft
basic files start with two bytes which indicate the length.  Text
files have no header at all.  DeImage compensates for these
offsets -- this is what the variable OFF in the program refers
to.  It was sort of a pain figuring this out, and it is why the
loading/saving is a little convoluted.  I have it load the first
chunk into $3FFC so the the data itself starts at $4000, but then
subsequent chunks have to be loaded at $4000, which means each
page is then filled with each sector rather than being four bytes
short, so the SAVE routine has to be aware of that.  And further
I have to be aware that a file which is, say, 1024 bytes long
actually has 5 data sectors because there is a four-byte "spill"
into the last sector.  Ick.  ProDOS is much nicer, because it
keeps all the file information in the catalog.  If you're
ambitious, try to get it to deal with text or Integer files.

Ok, enjoy.